openapi: 3.0.1
info:
  title: Custom Fields API
  description: >-
    Provides access to the custom fields that are part of a Hyperproof
    organization.
  version: '1.0'
servers:
  - url: https://api.hyperproof.app/v1/customfields
    description: Hyperproof US
  - url: https://api.hyperproofgov.app/v1/customfields
    description: Hyperproof Gov
  - url: https://api.hyperproof.eu/v1/customfields
    description: Hyperproof EU
security:
  - oauth2: []
paths:
  /:
    get:
      summary: Get Custom Fields
      description: >
        `GET /`


        #### Description


        Retrieves a list of all custom fields defined within an organization,
        including their names, data types, and associated entities.
      operationId: get-customfields
      parameters:
        - name: objectType
          in: query
          description: Filters custom fields by the provided object type
          schema:
            $ref: '#/components/schemas/ObjectType'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldCollection'
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.hyperproof.app/oauth/token
          scopes:
            customfield.read: Grants read access to custom fields
  schemas:
    ObjectStatus:
      type: string
      description: The status of the object
      enum:
        - active
        - archived
    ObjectTypeCollection:
      type: array
      items:
        $ref: '#/components/schemas/ObjectType'
    ObjectType:
      type: string
      description: The type of the object.
      enum:
        - audit
        - connection
        - control
        - controlScope
        - domain
        - freshnessHistory
        - exportFile
        - label
        - organization
        - organizationUser
        - policy
        - program
        - proof
        - request
        - requirement
        - risk
        - riskRegister
        - section
        - task
        - scope
        - template
        - user
    CustomFieldBehavior:
      type: string
      enum:
        - controlManaged
        - controlIndependent
        - controlAggregatedAverage
        - controlAggregatedMinimum
        - controlAggregatedMaximum
        - controlAggregatedSum
    CustomFieldCollection:
      type: array
      items:
        $ref: '#/components/schemas/CustomField'
      example:
        - id: d88d505d-5199-11ee-a644-522476618ae8
          orgId: ce83e3cd-5199-11ee-a644-522476618ae8
          name: Location
          type: textSingleSelect
          availableOn:
            - control
            - risk
          icon: Location
          isRequired: false
          options:
            - id: cc4a964b-804a-11ef-ba62-8e1e9aaad39g
              orgId: 509d0e22-1214-11ee-8157-8a23fb902dda
              fieldId: cc48c189-804a-11ef-ba62-8e1e9aaad39d
              isDefault: false
              textValue: Europe
            - id: cc4a964b-804a-11ef-ba62-8e1e9aaad345
              orgId: 509d0e22-1214-11ee-8157-8a23fb902dda
              fieldId: cc48c189-804a-11ef-ba62-8e1e9aaad39d
              isDefault: false
              textValue: North America
          status: active
          createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
          createdOn: '2023-09-12T18:26:10.005365Z'
          updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
          updatedOn: '2023-09-12T18:26:10.005365Z'
          permissions: []
    CustomField:
      type: object
      properties:
        id:
          type: string
        orgId:
          type: string
        name:
          type: string
        type:
          $ref: '#/components/schemas/CustomFieldType'
        behavior:
          $ref: '#/components/schemas/CustomFieldBehavior'
        availableOn:
          $ref: '#/components/schemas/ObjectTypeCollection'
        icon:
          $ref: '#/components/schemas/Icon'
        isRequired:
          type: boolean
        defaultTextValue:
          type: string
        defaultDateValue:
          type: string
        defaultNumberValue:
          type: number
          format: double
        options:
          $ref: '#/components/schemas/CustomFieldOptionCollection'
        numberFormat:
          type: string
          enum:
            - decimal
            - percentage
        status:
          $ref: '#/components/schemas/ObjectStatus'
        createdBy:
          type: string
        createdOn:
          type: string
        updatedBy:
          type: string
        updatedOn:
          type: string
        permissions:
          type: array
          items:
            type: string
      required:
        - id
        - orgId
        - name
        - type
        - isRequired
        - icon
        - options
        - numberFormat
      example:
        id: d88d505d-5199-11ee-a644-522476618ae8
        orgId: ce83e3cd-5199-11ee-a644-522476618ae8
        name: Location
        type: textSingleSelect
        availableOn:
          - control
          - risk
        icon: Location
        isRequired: false
        options:
          - id: cc4a964b-804a-11ef-ba62-8e1e9aaad39g
            orgId: 509d0e22-1214-11ee-8157-8a23fb902dda
            fieldId: cc48c189-804a-11ef-ba62-8e1e9aaad39d
            isDefault: false
            textValue: Europe
          - id: cc4a964b-804a-11ef-ba62-8e1e9aaad345
            orgId: 509d0e22-1214-11ee-8157-8a23fb902dda
            fieldId: cc48c189-804a-11ef-ba62-8e1e9aaad39d
            isDefault: false
            textValue: North America
        status: active
        createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        createdOn: '2023-09-12T18:26:10.005365Z'
        updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        updatedOn: '2023-09-12T18:26:10.005365Z'
        permissions: []
    CustomFieldOptionCollection:
      type: array
      items:
        $ref: '#/components/schemas/CustomFieldOption'
    CustomFieldOption:
      type: object
      properties:
        id:
          type: string
        orgId:
          type: string
        fieldId:
          type: string
        isDefault:
          type: boolean
        textValue:
          type: string
    CustomFieldType:
      type: string
      enum:
        - text
        - number
        - date
        - user
        - textSingleSelect
        - textMultiSelect
    Icon:
      type: string
      enum:
        - calendar1
        - calendar2
        - person
        - people
        - location
        - horizontalBar
        - explodedDonut
        - explodedPie
        - clock
        - applicationServer
        - airplane
        - gear
        - phone
        - fileServer
        - table
        - gauge1
        - gauge2
        - paperclip
        - flag
        - ship
        - folder
        - file
        - truck
        - bug
        - signPost
        - officeBuilding
        - map
        - servers
        - money
        - key
        - application
        - factory
        - workstation
        - book
        - filter
        - globe
        - mobilePhone
        - battery
        - spade
        - heart
        - diamond
        - club
        - star
        - clover
        - gem
        - box
        - fire
        - question
        - risk
        - doubleTick
        - refresh
        - tick
        - notStarted
        - cancelled
        - tag
